Skip to main content

URI Format

This document defines the standard for URI formats for ITEMs.

NDEF URL Format​

Due to the restriction in the NdefApplet v1.0.0 where the base URL was only allowed to be 17 bytes, the following URI standard was devised:

<DOMAIN_NAME>/<PATH_ITEM_ID>/<PATH_ITEM_INFO_HASH>?<QUERY_PARAM_NAME>=
  • Domain Name (<DOMAIN_NAME>): the domain name used in NDEF applet.
    • It should be always set to itm.st.
    • Fixed to 6 chars.
  • Path ITEM Identifier (<PATH_ITEM_ID>): represents the product or OEM identifier that the ITEM System's technology is placed.
    • For example, ob stands for OneBand and mp for Metal Plaques.
    • Maximum of 2 chars.
  • Path ITEM Info Hash (<PATH_ITEM_INFO_HASH>): represents some information about the ITEM ID/object, in a hash format. It can be, e.g., the software version running in the ITEM ID/object. Due to size constraints, this is the first 4 chars of the version SHA-256 hash.
    • For example, 2485 is the SHA-256("v1.0.0"), while d403 is the SHA-256("dk1").
    • See how to generate the hash in this section.
    • Maximum of 4 chars.
  • Query Param Name (QUERY_PARAM_NAME): represents the query parameter name followed by the equal sign (=).
    • It should be always set to d, of "data".
    • The data carries the so-called "augmented data", and the format is documented here.
    • Fixed to 1 char.

Some examples:

  • Consensus 2023, with OneBand: itm.st/ob/d403?d=
  • Token2049 2023, with OneBand: itm.st/ob/d403?d=
  • Denver Walls 2023, with Metal Plaques: itm.st/mp/2485?d=
  • Consensus 2024, with OneBand: itm.st/ob/2485?d=

Generating the ITEM Info Hash​

Some useful commands and its respective outputs:

  • Version: v1.0.0:

    • Generate the hash:

      echo -n "v1.0.0" | shasum -a 256 | cut -c 1-4

    • Response:

      2485

  • Version: dk1:

    • Generate the hash:

      echo -n "dk1" | shasum -a 256 | cut -c 1-4

    • Response:

      d403